<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
        <title>AJ Utils-A Clean and Clear Java Date API</title>
        <meta name="description" content="Small Java utilities with many useful functions. A Clean and Clear Java Date API" />
        <meta name="keywords" content="AJ Utils, ajaxjs, ajaxjs framework, java utilities, tools, helper, Date handling" />
        <meta name="viewport" content="width=device-width, initial-scale=1"/>
        <link rel="stylesheet" href="https://framework.ajaxjs.com/static/new-ui/css/common.css" />
        <link rel="stylesheet" href="https://iam.ajaxjs.com/asset/main.css"/>
        <link rel="icon" type="image/x-icon" href="https://framework.ajaxjs.com/aj-logo/logo.ico"/>
        <script src="https://framework.ajaxjs.com/static/aj-docs/common.js"></script>
        <script>
            // 获取用户的默认语言
            var userLang = navigator.language || navigator.userLanguage;

            // 检查是否为中文环境（包括简体和繁体）
            if (userLang.startsWith('zh') && location.pathname.indexOf('cn') == -1) {
                 confirm('欢迎！您可以改为访问中文内容。是否继续？') && location.assign('/cn');  // 如果是中文，则弹出提示
            }

            var _hmt = _hmt || [];
            (function() {
              var hm = document.createElement("script");
              hm.src = "https://hm.baidu.com/hm.js?208c5aea11c52991bd1c3283e62ad0ce";
              var s = document.getElementsByTagName("script")[0];
              s.parentNode.insertBefore(hm, s);
            })();
        </script>
    </head>
    <body>
        <nav>
            <div>
                <div class="links">
                    <a href="/">🏠 Home</a>
                    | ⚙️ Source:
                    <a target="_blank" href="https://github.com/lightweight-component/aj-util">Github</a>/<a target="_blank" href="https://gitcode.com/lightweight-component/aj-util">Gitcode</a>
                    | 🚀 <a href="/cn">Chinese Version</a>
                </div>
                <h1>
                    <img src="https://framework.ajaxjs.com/aj-logo/logo.png" style="vertical-align: middle;height: 45px;margin-bottom: 6px;" />
                    AJ Utils
                </h1>
                <h3>Small Java Utils Library</h3>
            </div>
        </nav>
        <div>
            <menu>
                
                <ul>
                    <li class="selected">
                        <a href="/">Home</a>
                    </li>
                </ul>
                <h3>Common</h3>
                <ul>
                    <li><a href="/common/JsonUtil/">JsonUtil</a></li>
                    <li><a href="/common/BytesHelper/">BytesHelper</a></li>
                    <li><a href="/common/ConvertBasicValue/">ConvertBasicValue</a></li>
                    <li><a href="/common/MessageDigestHelper/">HashHelper</a></li>
                    <li><a href="/common/MapTool/">MapTool</a></li>
                    <li><a href="/common/ObjectHelper/">ObjectHelper</a></li>
                    <li><a href="/common/RandomTools/">RandomTools</a></li>
                    <li><a href="/common/RegExpUtils/">RegExpUtils</a></li>
                    <li><a href="/common/StrUtil/">StrUtil</a></li>
                    <li><a href="/common/BoxLogger/">BoxLogger</a></li>
                    <li><a href="/common/BytesHelper/">BytesHelper</a></li>
                    <li><a href="/common/EncodeTools/">UrlEncode</a></li>
                    <li><a href="/common/XmlHelper/">XmlHelper</a></li>
                    <li><a href="/common/WebUtils/">WebUtils</a></li>
                </ul>
                <h3>Date Handing</h3>
                <ul>
                    <li><a href="/date/intro/">Introduction</a></li>
                    <li><a href="/date/convert/">Date Converter</a></li>
                    <li><a href="/date/formatter/">Date Formatter</a></li>
                </ul>
                <h3>Reflection</h3>
                <ul>
                    <li><a href="/reflect/Methods/">Methods</a></li>
                    <li><a href="/reflect/Types/">Types</a></li>
                    <li><a href="/reflect/Clazz/">Clazz</a></li>
                </ul>

                <h3>IO</h3>
                <ul>
                    <li><a href="/io/FileHelper/">FileHelper</a></li>
                    <li><a href="/io/Resources/">Resources</a></li>
                    <li><a href="/io/StreamHelper/">DataReader/DataWriter</a></li>
                    <li><a href="/io/ZipHelper/">ZipHelper</a></li>
                </ul>

                <h3>HTTP Request</h3>
                <ul>
                    <li><a href="/http_request/Get">HTTP Request</a></li>
                    <li><a href="/http_request/advanced-usage/">Advanced Usage</a></li>
                    <li><a href="/http_request/Base/">Base</a></li>
                </ul>
    
               <h3>Cryptography</h3>
               <ul>
                <li><a href="/cryptography/intro/">Introduction</a></li>
                <li><a href="/cryptography/flow/">Basic Flow</a></li>
                <li><a href="/cryptography/AesCrypto/">AES/DES</a></li>
                <li><a href="/cryptography/RsaCrypto/">RSA</a></li>
               </ul>
            </menu>
            <article class="aj-text">
                <h1>A Clean and Clear Java Date API</h1>
<p>When it comes to date types, they are relatively more tricky to handle compared to other primitive data types (int/long/boolean/string), and there are multiple reasons for this. Firstly, date is a broad concept - year-month-day can be called a date, year-month-day-hour-minute-second can also be called a date, or even just hour-minute-second alone can be considered a date. So which date are you actually referring to? The traditional Java date type <code>java.util.Date</code> does exactly this - one type encompasses all the above date concepts, which is the root cause of the混乱 in date APIs. Secondly, the way dates are expressed, also known as &quot;format&quot;, can be <code>2025-12-22 11:05</code>, or <code>2025-12-22 11-05</code> or even <code>3 Jun 2025 11:05</code>, with many varieties. Finally, dates also have the concept of time zones, such as <code>2024-12-03T10:15:30+01:00[Europe/Paris]</code>, <code>Tue, 3 Jun 2025 11:05:30 GMT</code>, etc.</p>
<h2>About the <code>Date</code> Type</h2>
<p>In early Java versions, the <code>java.util.Date</code> type dominated everything, with many date processing methods built around it (before Java 1.1). In later version refactoring, many of these methods were deprecated and replaced by <code>java.util.Calendar</code> and <code>java.text.DateFormat</code>. Did Calendar solve the tricky date problems? Not really. Although Calendar handles dates more flexibly, it is still overly complex to use, and setting, comparing, and formatting remain troublesome and verbose. Therefore, the community came up with a replacement - Joda-Time, which was adopted by many projects. This excellent open-source project gradually became part of the Java standard, known as JSR310, and was finally integrated into Java 8 as <code>java.time</code>!</p>
<p>In summary, the date types we advocate using are <code>Instant</code> and <code>LocalDateTime</code> from <code>java.time</code>. <code>Instant</code> represents a moment in time, roughly corresponding to a timestamp, and can support nanosecond precision. <code>LocalDateTime</code> might be more commonly used by us, along with its other derived precise types.</p>
<h3>📅 New Java Common Date/Time Types</h3>
<table>
<thead>
<tr>
<th>Type</th>
<th>Package</th>
<th>Java Version</th>
<th>Description</th>
<th>Recommended</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Instant</code></td>
<td><code>java.time.Instant</code></td>
<td>8+</td>
<td>Represents an instantaneous point on the timeline (UTC), precise to nanoseconds</td>
<td>✅ Recommended for timestamps</td>
</tr>
<tr>
<td><code>LocalDate</code></td>
<td><code>java.time.LocalDate</code></td>
<td>8+</td>
<td><strong>Date only</strong> (year-month-day), such as <code>2025-03-08</code></td>
<td>✅ Strongly recommended for &quot;pure date&quot; scenarios (such as train departure dates)</td>
</tr>
<tr>
<td><code>LocalTime</code></td>
<td><code>java.time.LocalTime</code></td>
<td>8+</td>
<td><strong>Time only</strong> (hour:minute:second.nanosecond), such as <code>14:30:00</code></td>
<td>✅ Recommended for &quot;pure time&quot; scenarios (such as departure times)</td>
</tr>
<tr>
<td><code>LocalDateTime</code></td>
<td><code>java.time.LocalDateTime</code></td>
<td>8+</td>
<td>Date + Time (no time zone), such as <code>2025-03-08T14:30:00</code></td>
<td>✅ Recommended for local time (such as train schedules)</td>
</tr>
<tr>
<td><code>ZonedDateTime</code></td>
<td><code>java.time.ZonedDateTime</code></td>
<td>8+</td>
<td>Date/time with time zone, supports daylight saving time, etc.</td>
<td>✅ Recommended for cross-timezone systems</td>
</tr>
<tr>
<td><code>OffsetDateTime</code></td>
<td><code>java.time.OffsetDateTime</code></td>
<td>8+</td>
<td>Time with offset (such as <code>+08:00</code>)</td>
<td>✅ Suitable for storing database times</td>
</tr>
<tr>
<td><code>Duration</code></td>
<td><code>java.time.Duration</code></td>
<td>8+</td>
<td>Represents a time period (seconds, nanoseconds), such as 2 hours</td>
<td>✅ Recommended for calculating time differences</td>
</tr>
<tr>
<td><code>Period</code></td>
<td><code>java.time.Period</code></td>
<td>8+</td>
<td>Represents a time period (years, months, days), such as 1 month later</td>
<td>✅ Recommended for calendar period calculations</td>
</tr>
<tr>
<td><code>DateTimeFormatter</code></td>
<td><code>java.time.format.DateTimeFormatter</code></td>
<td>8+</td>
<td>Thread-safe formatting/parsing tool</td>
<td>✅ Replacement for <code>SimpleDateFormat</code></td>
</tr>
</tbody>
</table>
<p>So is the Date type completely obsolete and unused? ——Not exactly. Although the related APIs around Date were deprecated as early as after Java 1.1, this doesn't mean the Date type itself is deprecated. If it were deprecated, why wouldn't you find the <code>@Deprecated</code> annotation in the new JDK17? This indicates that the type is still retained. Using Date as a value object (Value Object) itself isn't problematic. For example, two constructor usages are still retained: <code>new Date()</code> and <code>new Date(long timestamp)</code>.</p>
<h2>API Introduction</h2>
<p>This date API encapsulated by the author mainly has three functions:</p>
<ol>
<li>Date type conversion. Facing such a variety of date types: Date, Instant, Int/Long/String, LocalDate/LocalDateTime/LocalTime, ZonedDateTime, etc., providing methods that can convert between each other, i.e., input <code>T returned date = input(Object anyType).to(Class&lt;T&gt; expected type)</code>.</li>
<li>Universal date formatting.</li>
<li><code>now()</code> function that returns the current date and other utility functions.</li>
</ol>
<p>Source code at: <a href="https://gitee.com/lightweight-components/aj-util/tree/main/aj-util/src/main/java/com/ajaxjs/util/date">https://gitee.com/lightweight-components/aj-util/tree/main/aj-util/src/main/java/com/ajaxjs/util/date</a>.</p>

            </article>
        </div>

       <footer>
            AJ-Util, a part of <a href="https://framework.ajaxjs.com" target="_blank">AJ-Framework</a> open source. Mail:
            frank@ajaxjs.com, visit <a href="https://blog.csdn.net/zhangxin09" target="_blank">my blog(In Chinese)</a>.
            <br />
            <br />
            Copyright © 2025 Frank Cheung. All rights reserved.
        </footer>
    </body>
</html>